For various reasons noted below, printing is not enabled by default for all ODF parts. This document describes how to add printing to your ODF part if you decide to support printing. See also the Draw and Form samples where printing is implemented.
Why You Need to Do Anything at All
Here are the reasons why printing is not enabled by default. There are parts for which it does not make sense to print; ODFClock and ODFButton are two examples. A part that doesn’t print should not pay the price (in code size) for a feature it doesn’t use. Putting printing code directly into FW_CPart or FW_CFrame would make it very difficult to take advantage of code deadstripping.
Note that only the topmost part in a document needs to support printing. Naturally you would want ODFClock or ODFButton to print if they are part of another document. If their container part supports printing, they will get printed as well. Thus, you only need to support printing if you expect your part to be used outside of a printing embedding part.
Overview
In ODF/OpenDoc, it is frames that are printed. Frames print by drawing to a special facet, which is created for them by the printing code. On the Macintosh, ODF printing supports Quickdraw GX and Quickdraw, both in the same print job. This is so that if you have embedded GX and non-GX parts, they all print on the same piece of paper, in the same print job.
Printing Classes
FW_CPrintInfo
This class, defined in FWPrInfo.h, encapsulates print/page setup information: printer name, number of copies to print, page boundaries, etc. It contains methods to get to the platform data structures (gxJob, THPrint on the Mac, PRINTDLG on Windows).
FW_CPrintEnvironment
This class, defined in FWPrInfo.h, makes sure that whenever ODF makes printing calls, the Macintosh print driver will be open. Constructors in some printing classes take a reference to this class. On Windows and under Quickdraw GX, this class does nothing.
FW_CPrintJob
This class, defined in FWPrInfo.h, encapsulates a running platform print job. There are calls to open/close the document and pages, and to handle printing errors.
FW_CPrintHandler
This class, defined in FWPrHdlr.h, contains all the logic necessary to handle page setup and actual printing. It interacts with the part, the frame, and other print classes to produce a printed image of the frame.
Basic Printing
Changes to Your Root Frame Class
The only change necessary to activate the Print menu commands and support basic printing of the current frame is to override FW_CFrame::NewPrintHandler and add the following code:
return new FW_CPrintHandler(part, this); // print handler base class
}
ODF uses the content view's extent to determine how much to print.
If your frame is only printable some of the time, depending on the content, you should subclass FW_CPrintHandler and override IsCurrentlyPrintable and return TRUE only if your frame can be printed at the time. For example, the ODFDraw sample part only prints when there is at least one shape in the drawing.
return new CMyPrintHandler(part, this); // custom print handler
}
Linking with QuickDrawGXLib
On the Macintosh, you should link with QuickDrawGXLib in order to support QuickDraw GX printing. Make sure that you use a “weak” reference, so your part runs even when Quickdraw GX is not installed (in which case only standard printing is supported).
Adding a Progress Dialog
On the Macintosh you can add a standard "progress dialog" with a Cancel button that will be displayed while the print job is being executed. This is only useful for non-background printing since a background print job can be controlled directly in the Print Manager window.
To add the progress dialog simply add the following resource file to your project:
ODF:Framewrk:FWPart:Other:FWPrint.r
Determining if Drawing to the Screen or Printing
Often you will want to draw your frame slightly differently when you print. For example, it usually doesn’t make sense to print grid lines and such. To help you decide how to draw, you can check the facet’s canvas for a platform print job, and/or check if the facet is dynamic. For example:
Note that for the Macintosh, the code checks for both Quickdraw GX and Quickdraw print jobs. This is because ODF will use a Quickdraw GX print job whenever possible and resort to Print Manager calls only when GX is not available.
Advanced Printing
Subclassing FW_CPrintHandler
If you want to change some aspects of ODF printing, you will need to subclass FW_CPrintHandler, override the appropriate methods, and create an instance of this subclass in your frame's NewPrintHandler method.
Using a Separate View for Printing
Some parts may want to use a completely different layout when printing. For example, it doesn’t make sense to print scroll bars, and removing them may affect where embedded frames are positioned. ODF provides hooks so that you can create a special view that will be printed. This special view, knowing that it is created specifically for printing, can create a different layout that will then be printed.
To accomplish this, you need to override the CreatePrintView and ReleasePrintView methods, and do your layout negotiation in CountPrintPages.
Modifying Print Dialogs
Some parts may want to change the default print dialogs used by ODF (which just makes the most basic platform calls). To do this, you can override DoPageSetupDialog and DoJobDialog.
To change the way the user is notified of a printing error or that printing has been cancelled, override NotifyNoDefaultPrinter and NotifyPrintingCanceled.
You can also override the print progress dialog. To do this, you should override CreateProgressDialog, UpdateProgressDialog and DestroyProgressDialog. If you do this, you are also responsible for implementing an abort/idle proc and setting it in the print job (using SetAbortProc(hDC...) on Windows or pIdleProc on the Macintosh).
